Building the Docs
=================

This guide explains how to compile the Clera documentation from source
using Sphinx. Follow these steps any time you update ``.rst`` files and
want to regenerate the HTML output.

Prerequisites
-------------

You need Python 3.7+ and ``pip`` installed. Install the required
packages once:

.. code:: bash

   pip install sphinx sphinx-book-theme

Verify Sphinx is available:

.. code:: bash

   sphinx-build --version

Project Structure
-----------------

The documentation lives in the ``rtd/`` folder:

::

   rtd/
   ├── Makefile          # Linux / macOS build script
   ├── make.bat          # Windows build script
   ├── source/
   │   ├── conf.py       # Sphinx configuration
   │   ├── index.rst     # Table of contents root
   │   ├── _pages/       # All documentation pages (.rst files)
   │   ├── _static/      # Static assets (CSS, images, favicon)
   │   └── _templates/   # Optional Jinja2 HTML templates
   └── build/
       └── html/         # Generated HTML output (after build)

Building the HTML
-----------------

**Step 1 — Open a terminal and navigate to the** ``rtd/`` **folder:**

.. code:: bash

   cd path/to/your/project/rtd

**Step 2 — Run the build command:**

On Linux / macOS:

.. code:: bash

   make html

On Windows:

.. code:: bash

   make.bat html

Sphinx will read ``source/conf.py``, process all ``.rst`` files, and
write the rendered HTML into ``build/html/``.

**Step 3 — Open the output in your browser:**

.. code:: bash

   # Linux / macOS
   open build/html/index.html

   # Windows
   start build/html/index.html

Cleaning the Build
------------------

If you encounter stale output or want a full rebuild, clean the
``build/`` directory first:

On Linux / macOS:

.. code:: bash

   make clean
   make html

On Windows:

.. code:: bash

   make.bat clean
   make.bat html

Alternatively, delete the ``build/`` folder manually and re-run the
build command.

Updating the Version Number
---------------------------

The release version displayed in the docs is set in ``source/conf.py``:

.. code:: python

   release = '0.3.0'

Update this string whenever you cut a new release, then rebuild.

Adding a New Page
-----------------

1. Create a new ``.rst`` file inside ``source/_pages/``.

2. Open ``source/index.rst`` and add the file path (without the
   ``.rst`` extension) to the ``toctree`` directive:

   .. code:: rst

      .. toctree::
         :maxdepth: 2
         :hidden:

         _pages/Your New Page

3. Rebuild with ``make html``.

Deploying to Read the Docs
--------------------------

The repository includes a ``readthedocs.yaml`` configuration file at
the ``rtd/`` root. When connected to a Read the Docs account:

1. Push your changes to the linked repository.

2. Read the Docs will detect the ``readthedocs.yaml`` file, install
   dependencies from ``source/requirements.txt``, and build the docs
   automatically.

3. The live docs URL will update within a few minutes.

To trigger a manual rebuild, log in to your Read the Docs dashboard,
select the project, and click **Build**.

Troubleshooting
---------------

-  **sphinx-build: command not found** — Run ``pip install sphinx`` and
   ensure your Python ``Scripts`` (Windows) or ``bin`` (Linux/macOS)
   directory is on your ``PATH``.

-  **Theme not found error** — Run ``pip install sphinx-book-theme``.

-  **Broken references or warnings** — Sphinx prints the file and line
   number. Fix the ``.rst`` source file and rebuild.

-  **Stale pages not updating** — Run ``make clean`` before ``make html``
   to force a full rebuild.